TypeScript 身份验证：面向全球应用的 JWT 类型安全模式

在当今互联互通的世界中，构建安全可靠的全球应用程序至关重要。身份验证（验证用户身份的过程）在保护敏感数据和确保授权访问方面起着关键作用。JSON Web Tokens (JWT) 因其简单性和可移植性而成为实现身份验证的流行选择。当与 TypeScript 强大的类型系统结合使用时，JWT 身份验证可以变得更加强大和可维护，尤其是在大型国际项目中。

为什么使用 TypeScript 进行 JWT 身份验证？

在构建身份验证系统时，TypeScript 具有以下几个优势：

• 类型安全： TypeScript 的静态类型有助于在开发过程的早期发现错误，从而降低运行时出现意外情况的风险。这对于像身份验证这样对安全性敏感的组件至关重要。
• 改进的代码可维护性： 类型提供了清晰的合同和文档，使理解、修改和重构代码变得更加容易，尤其是在涉及多个开发人员的复杂全球应用程序中。
• 增强的代码完成和工具： 能够识别 TypeScript 的 IDE 提供更好的代码完成、导航和重构工具，从而提高开发人员的生产力。
• 减少样板代码： 接口和泛型等功能可以帮助减少样板代码并提高代码的可重用性。

了解 JWT

JWT 是一种紧凑的、URL 安全的表示要在两方之间传输的声明的方法。它由三个部分组成：

1. 标头： 指定算法和令牌类型。
2. 有效负载： 包含声明，例如用户 ID、角色和过期时间。
3. 签名： 使用密钥确保令牌的完整性。

JWT 通常用于身份验证，因为可以在服务器端轻松验证它们，而无需为每个请求查询数据库。但是，通常不鼓励将敏感信息直接存储在 JWT 有效负载中。

在 TypeScript 中实现类型安全的 JWT 身份验证

让我们探讨一些在 TypeScript 中构建类型安全的 JWT 身份验证系统的模式。

1. 使用接口定义有效负载类型

首先定义一个接口，表示 JWT 有效负载的结构。这可确保您在访问令牌中的声明时具有类型安全。

interface JwtPayload {
  userId: string;
  email: string;
  roles: string[];
  iat: number; // Issued At (timestamp)
  exp: number; // Expiration Time (timestamp)
}

此接口定义了 JWT 有效负载的预期形状。我们包含了标准 JWT 声明，如 `iat`（签发时间）和 `exp`（过期时间），这对于管理令牌的有效性至关重要。您可以添加任何其他与您的应用程序相关的声明，如用户角色或权限。最好将声明限制为仅必要的信息，以最大限度地减少令牌大小并提高安全性。

示例：在全球电子商务平台中处理用户角色

考虑一个为全球客户提供服务的电子商务平台。不同的用户具有不同的角色：

• 管理员： 完全访问权限来管理产品、用户和订单。
• 卖家： 可以添加和管理自己的产品。
• 客户： 可以浏览和购买产品。

`JwtPayload` 中的 `roles` 数组可用于表示这些角色。您可以将 `roles` 属性扩展为更复杂的结构，以精细的方式表示用户的访问权限。例如，您可以拥有一系列允许用户作为卖家运营的国家/地区列表，或者用户具有管理员访问权限的商店数组。

2. 创建类型化的 JWT 服务

创建一个处理 JWT 创建和验证的服务。此服务应使用 `JwtPayload` 接口来确保类型安全。

import jwt from 'jsonwebtoken';

const JWT_SECRET = process.env.JWT_SECRET || 'your-secret-key'; // Store securely!

class JwtService {
  static sign(payload: Omit, expiresIn: string = '1h'): string {
    const now = Math.floor(Date.now() / 1000);
    const payloadWithTimestamps: JwtPayload = {
        ...payload,
        iat: now,
        exp: now + parseInt(expiresIn) * 60 * 60,
    };
    return jwt.sign(payloadWithTimestamps, JWT_SECRET);
  }

  static verify(token: string): JwtPayload | null {
    try {
      const decoded = jwt.verify(token, JWT_SECRET) as JwtPayload;
      return decoded;
    } catch (error) {
      console.error('JWT verification error:', error);
      return null;
    }
  }
}

此服务提供两种方法：

• `sign()`： 从有效负载创建 JWT。它采用 `Omit` 以确保自动生成 `iat` 和 `exp`。安全地存储 `JWT_SECRET` 非常重要，最好使用环境变量和密钥管理解决方案。
• `verify()`： 验证 JWT，如果有效，则返回解码的有效负载；如果无效，则返回 `null`。我们在验证后使用类型断言 `as JwtPayload`，这是安全的，因为 `jwt.verify` 方法要么抛出错误（在 `catch` 块中捕获），要么返回一个与我们定义的有效负载结构匹配的对象。

重要的安全注意事项：

• 密钥管理： 永远不要在代码中硬编码您的 JWT 密钥。使用环境变量或专用密钥管理服务。定期轮换密钥。
• 算法选择： 选择一种强大的签名算法，如 HS256 或 RS256。避免使用弱算法，如 `none`。
• 令牌过期： 为您的 JWT 设置适当的过期时间，以限制泄露的令牌的影响。
• 令牌存储： 在客户端安全地存储 JWT。选项包括 HTTP-only Cookie 或具有适当的防止 XSS 攻击的预防措施的本地存储。

3. 使用中间件保护 API 端点

创建中间件以通过验证 `Authorization` 标头中的 JWT 来保护您的 API 端点。

import { Request, Response, NextFunction } from 'express';

interface RequestWithUser extends Request {
  user?: JwtPayload;
}

function authenticate(req: RequestWithUser, res: Response, next: NextFunction) {
  const authHeader = req.headers.authorization;

  if (!authHeader) {
    return res.status(401).json({ message: 'Unauthorized' });
  }

  const token = authHeader.split(' ')[1]; // Assuming Bearer token
  const decoded = JwtService.verify(token);

  if (!decoded) {
    return res.status(401).json({ message: 'Invalid token' });
  }

  req.user = decoded;
  next();
}

export default authenticate;

此中间件从 `Authorization` 标头中提取 JWT，使用 `JwtService` 验证它，并将解码的有效负载附加到 `req.user` 对象。我们还定义了一个 `RequestWithUser` 接口来扩展 Express.js 中的标准 `Request` 接口，添加了一个类型为 `JwtPayload | undefined` 的 `user` 属性。这在访问受保护路由中的用户信息时提供了类型安全。

示例：在全球应用程序中处理时区

假设您的应用程序允许来自不同时区的用户安排事件。您可能希望将用户的首选时区存储在 JWT 有效负载中，以正确显示事件时间。您可以将 `timeZone` 声明添加到 `JwtPayload` 接口：

interface JwtPayload {
  userId: string;
  email: string;
  roles: string[];
  timeZone: string; // e.g., 'America/Los_Angeles', 'Asia/Tokyo'
  iat: number;
  exp: number;
}

然后，在您的中间件或路由处理程序中，您可以访问 `req.user.timeZone` 以根据用户的偏好格式化日期和时间。

4. 在路由处理程序中使用经过身份验证的用户

在您的受保护路由处理程序中，您现在可以通过 `req.user` 对象访问经过身份验证的用户的信息，并具有完全的类型安全。

import express, { Request, Response } from 'express';
import authenticate from './middleware/authenticate';

const app = express();

app.get('/profile', authenticate, (req: Request, res: Response) => {
  const user = (req as any).user; // or use RequestWithUser
  res.json({ message: `Hello, ${user.email}!`, userId: user.userId });
});

此示例演示了如何从 `req.user` 对象访问经过身份验证的用户的电子邮件和 ID。由于我们定义了 `JwtPayload` 接口，因此 TypeScript 知道 `user` 对象的预期结构，并且可以提供类型检查和代码完成。

5. 实现基于角色的访问控制 (RBAC)

对于更细粒度的访问控制，您可以根据存储在 JWT 有效负载中的角色来实现 RBAC。

function authorize(roles: string[]) {
  return (req: RequestWithUser, res: Response, next: NextFunction) => {
    const user = req.user;

    if (!user || !user.roles.some(role => roles.includes(role))) {
      return res.status(403).json({ message: 'Forbidden' });
    }

    next();
  };
}

此 `authorize` 中间件检查用户的角色是否包含任何必需的角色。如果没有，则返回 403 Forbidden 错误。

app.get('/admin', authenticate, authorize(['admin']), (req: Request, res: Response) => {
  res.json({ message: 'Welcome, Admin!' });
});

此示例保护 `/admin` 路由，要求用户具有 `admin` 角色。

示例：在全球应用程序中处理不同的货币

如果您的应用程序处理金融交易，您可能需要支持多种货币。您可以将用户的首选货币存储在 JWT 有效负载中：

interface JwtPayload {
  userId: string;
  email: string;
  roles: string[];
  currency: string; // e.g., 'USD', 'EUR', 'JPY'
  iat: number;
  exp: number;
}

然后，在您的后端逻辑中，您可以使用 `req.user.currency` 来格式化价格并根据需要执行货币转换。

6. 刷新令牌

JWT 的设计寿命很短。为了避免要求用户频繁登录，请实施刷新令牌。刷新令牌是一种长寿命令牌，可用于获取新的访问令牌 (JWT)，而无需用户重新输入其凭据。将刷新令牌安全地存储在数据库中，并将它们与用户关联。当用户的访问令牌过期时，他们可以使用刷新令牌来请求新的访问令牌。需要仔细实施此过程，以避免安全漏洞。

高级类型安全技术

1. 用于细粒度控制的可辨识联合

有时，您可能需要基于用户的角色或请求类型使用不同的 JWT 有效负载。可辨识联合可以帮助您通过类型安全来实现此目的。

interface AdminJwtPayload {
  type: 'admin';
  userId: string;
  email: string;
  roles: string[];
  iat: number;
  exp: number;
}

interface UserJwtPayload {
  type: 'user';
  userId: string;
  email: string;
  iat: number;
  exp: number;
}

type JwtPayload = AdminJwtPayload | UserJwtPayload;

function processToken(payload: JwtPayload) {
  if (payload.type === 'admin') {
    console.log('Admin email:', payload.email); // Safe to access email
  } else {
    // payload.email is not accessible here because type is 'user'
    console.log('User ID:', payload.userId);
  }
}

此示例定义了两种不同的 JWT 有效负载类型 `AdminJwtPayload` 和 `UserJwtPayload`，并将它们组合成一个可辨识联合 `JwtPayload`。 `type` 属性充当鉴别器，允许您根据有效负载类型安全地访问属性。

2. 用于可重用身份验证逻辑的泛型

如果您有多个具有不同有效负载结构的身份验证方案，则可以使用泛型来创建可重用的身份验证逻辑。

interface BaseJwtPayload {
  userId: string;
  iat: number;
  exp: number;
}

function verifyToken(token: string): T | null {
  try {
    const decoded = jwt.verify(token, JWT_SECRET) as T;
    return decoded;
  } catch (error) {
    console.error('JWT verification error:', error);
    return null;
  }
}

const adminToken = verifyToken('admin-token');
if (adminToken) {
  console.log('Admin email:', adminToken.email);
}

此示例定义了一个 `verifyToken` 函数，该函数采用扩展 `BaseJwtPayload` 的泛型类型 `T`。这允许您验证具有不同有效负载结构的令牌，同时确保它们都至少具有 `userId`、`iat` 和 `exp` 属性。

全球应用程序注意事项

在为全球应用程序构建身份验证系统时，请考虑以下事项：

• 本地化： 确保错误消息和用户界面元素针对不同的语言和地区进行本地化。
• 时区： 在设置令牌过期时间以及向用户显示日期和时间时，正确处理时区。
• 数据隐私： 遵守数据隐私法规，如 GDPR 和 CCPA。最大限度地减少存储在 JWT 中的个人数据量。
• 可访问性： 将身份验证流程设计为可供残疾用户访问。
• 文化敏感性： 在设计用户界面和身份验证流程时，请注意文化差异。

结论

通过利用 TypeScript 的类型系统，您可以为全球应用程序构建强大且可维护的 JWT 身份验证系统。使用接口定义有效负载类型、创建类型化的 JWT 服务、使用中间件保护 API 端点以及实施 RBAC 是确保安全性和类型安全的关键步骤。通过考虑全球应用程序注意事项，如本地化、时区、数据隐私、可访问性和文化敏感性，您可以创建对不同的国际受众具有包容性和用户友好的身份验证体验。请记住，在处理 JWT 时始终优先考虑安全最佳实践，包括安全密钥管理、算法选择、令牌过期和令牌存储。拥抱 TypeScript 的强大功能，为您的全球应用程序构建安全、可扩展和可靠的身份验证系统。